Rewrite to a sphinx project and use unified theme by Cadair · Pull Request #698 · astropy/astropy.github.com

Cadair · 2026-01-19T16:30:57Z

You can see a preview of this here: https://astropy-org--698.org.readthedocs.build/

Fun things to checkout:

light and dark themes
the search!!

I think this is now ready for review, but please confine review to the diff in this PR. i.e. not the theme which should be reviewed here: astropy/astropy-sphinx-theme#48

HTML Pages left to port:

Todo before merge:

~~Find someone with power to move the astropy.org domain to RTD~~ punted to later
Be ready to reconfigure Github pages for actions upload
Add back Google Analytics, and start a discussion somewhere about improvements later
Merge theme PR and release astropy-sphinx-theme

Other potential improvements:

Use intersphinx for all links to core documentation
See if we can generate a dark theme variant of the home page background

Cadair · 2026-01-19T16:57:43Z

I'll keep a list of things I think we could tidy up here as I go along:

We should get rid of all the affiliated package javascript and have sphinx just do all the page gen on build. Then cronjob the site to rebuild each day or week or something.
The Copy bibtex js on the citation page inlines all the bibtex which is just horrible, we should have sphinx read that in from somewhere sane. What is the canonical source of the citation bibtex?
The javascript for the team page should all be removed and replaced with build-time Python code.

pllim · 2026-01-20T18:55:21Z

You will have to pull this change in too after it is merged. FYI

Filter out astropy core package from pyOpenSci Affiliated listing #699

Cadair · 2026-01-21T14:35:47Z

@astropy/astropy-website-maintainers This is now ready for review.

Cadair · 2026-01-21T14:42:54Z

+sphinx
+myst-parser
+sphinx-design
+astropy-sphinx-theme@git+https://github.com/Cadair/astropy-sphinx-theme@sunpy-astropy-theme


We should probably cut a release of astropy-sphinx-theme before merging this PR 😉

Can you pls cross link PR from that branch here for future reference? Thanks!

It's in the PR description above.

Oh right, nevermind. We cannot merge until this is resolved. I better block merge given the approval.

pllim · 2026-01-21T14:54:13Z

This is now ready for review

Shouldn't I wait for you to resolve #698 (comment) first?

Cadair · 2026-01-21T14:56:44Z

This is now ready for review

Shouldn't I wait for you to resolve #698 (comment) first?

No, I don't think so. This PR is not about the theme it's about rewriting the astropy.org site to use sphinx. Comments about the theme should go on the theme PR.

hamogu · 2026-01-21T16:22:00Z

Now for the record: I'm not a maintainer of this repro because I have deep experience with web development, it's because we used to manually update the list of affiliated packages in this repro and I was the affiliated package editor at the time (and are again now, though we know how've a difference mechanism).
@eteq is the person who usually reviews changes like this.

That said, I'll have a look as soon as I can.

hamogu

Most of the changes are pretty straightforward changes for html->rst. I'm not saying that to diminish @Cadair 's work (I know it's still a lot of work to do that, but it's not conceptually hard), just to say that the review is basically "it works" and there is no need to review every changed line, because we would not want to include any changes in the wording of individual pages here anyway.
Otherwise, it's a pretty standard setup and I see no problems with it.

hamogu · 2026-01-21T16:28:22Z

+// Quirk to note: the jQuery.getJSON function fails if you open this locally
+// with Chrome, because Chrome thinks local JSON files are unsafe for some
+// reason.  Use basically any other modern browser, or it works fine if its
+// actually on the web server even with chrome.


Not really important here, since this is just a comment anyway, but I think most modern browsers now refuse to load any local file for security - for testing locally you'll a local web server running for all or most of them.

yeah this comment is pretty old 😆

I'd like to purge this entire file of js if I have the time.

pllim · 2026-01-22T22:33:50Z

You have to resolve conflict to pick up #699 . Thanks!

Cadair · 2026-01-27T13:44:18Z

Merged in main

pllim · 2026-01-27T15:10:30Z

Hmm something is wrong.

Cadair · 2026-01-27T15:13:43Z

Looks like that's a circleci problem, the way that circleci previews somethings doesn't really work properly. If you look at the RTD preview it seems to work.

pllim · 2026-01-27T15:15:40Z

Thanks for the clarification. I hope you are right...

pllim · 2026-01-27T15:16:32Z

So this is good to merge or are we waiting on something else?

pllim · 2026-01-27T15:18:13Z

Can you please add comment to explain what this is for, for future reference?

pllim

Also... Don't we also use some sort of banner mechanism here that "talks" with astropy cord RTD, like when we announced the 10k citation stuff. Would that still work?

pllim · 2026-01-27T15:19:07Z

+sphinx
+myst-parser
+sphinx-design
+astropy-sphinx-theme@git+https://github.com/Cadair/astropy-sphinx-theme@sunpy-astropy-theme


Oh right, nevermind. We cannot merge until this is resolved. I better block merge given the approval.

Cadair · 2026-01-27T15:20:28Z

So this is good to merge or are we waiting on something else?

There's a todo list in the OP, but mostly it's blocked on people reviewing / approving / arguing about colours on the theme PR.

pllim

Waiting for sunpy theme release

Cadair · 2026-01-27T15:21:05Z

Also... Don't we also use some sort of banner mechanism here that "talks" with astropy cord RTD, like when we announced the 10k citation stuff. Would that still work?

Yes, but I should actually make this site display the banner if it's active!

use intersphinx for references to docs.astropy.org

Cadair · 2026-04-07T14:37:43Z

@eteq I think the latest commit f75fd07 (this PR) adds a workflow which can be configured to publish the built site to github pages.

I think there's still some configuration work to be done to make that actions based deployment work (github actions environment etc).

eteq

I'm generally happy with all of this, but I have a few questions about finalization steps, @Cadair :

The changes reminded me our release announcements are generally rendered here. I'm not sure how much we're using that in the more recent releases (@astrofrog might know?), but it's possible that some links will be broken by this if e.g. some of them assumed the github url instead of the astropy.org URL?
@Cadair, I'm not sure what the finalization was you had in mind here as your last few posts suggest different things to me: are you thinking to use the gh-actions build to mirror the RTD build to here and have this remain the "true" version? (which would then require no DNS change I think) Or just have this as an alternative build and still update the DNS to point to RTD?

eteq · 2026-05-06T16:13:17Z

In some out-of-band discussion, @Cadair clarified the answer is that the desired end-state is RTD only. But we want to take a phased approach since we're not sure what all might break in the transition. So the plan is:

Reconfigure astropy.github.com to build gh-pages from actions (in preperation for merge).
Merge the PR
See that astropy.org continues to work hosted by gh-pages
@eteq updates teh DNS
figure out what we need to do to disable gh-page or if we can't put a placeholder page up

I'll do 1/2 momentarily, and then we'll follow up with the rest elsewhere (since this will be merged by then)

eteq · 2026-05-06T16:25:03Z

I believe I have done step 1, so merging now

eteq · 2026-05-06T16:29:14Z

One additional step I realized was also needed: disableing the circleci webhook since it's not used post-merge.

Cadair force-pushed the unified-theme-rewrite branch from 4b2fc98 to af49c3f Compare January 19, 2026 16:49

Cadair force-pushed the unified-theme-rewrite branch 4 times, most recently from d351274 to d4640ba Compare January 20, 2026 17:17

This comment was marked as outdated.

Sign in to view

Cadair marked this pull request as ready for review January 20, 2026 17:20

Cadair changed the title ~~WIP: Rewrite to a sphinx project and use unified theme~~ Rewrite to a sphinx project and use unified theme Jan 20, 2026

Cadair mentioned this pull request Jan 20, 2026

Add substitutions to credits.rst for astropy.org site astropy/astropy#19192

Merged

1 task

Cadair commented Jan 21, 2026

View reviewed changes

Cadair mentioned this pull request Jan 21, 2026

Tracking Issue: Unified Astropy Sphinx Theme Migration astropy/astropy-project#522

Open

hamogu approved these changes Jan 21, 2026

View reviewed changes

pllim reviewed Jan 27, 2026

View reviewed changes

Comment thread .circleci/config.yml Outdated

pllim reviewed Jan 27, 2026

View reviewed changes

Comment thread exts/rawfiles.py

Copy link
Copy Markdown

Member

pllim Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please add comment to explain what this is for, for future reference?

pllim reviewed Jan 27, 2026

View reviewed changes

pllim requested changes Jan 27, 2026

View reviewed changes

Cadair added 16 commits February 5, 2026 16:07

TMP: Add CoC Pages

a73bb2f

TMP: Announcement Banner

a737703

TMP: About

1e1f89c

TMP: help

d6e4fb6

TMP: history

dce9fc5

TMP: team

2f9da79

TMP: Contributing

8b15918

TMP: 10k citations

7f61aa4

TMP: announcements

26ff776

add back Python helpers

066f8af

Some other cleanup

6c40ce8

Attempt to fix circlci

47c1761

Update .gitignore

073c927

Use theme in new home

e7e55f9

Remove now redundant subs

edab2ba

fix artifact path

f18d04b

Cadair force-pushed the unified-theme-rewrite branch from b122766 to f18d04b Compare February 5, 2026 16:07

Cadair added 4 commits February 5, 2026 16:17

Drop circleCI and use GitHub actions for checks

c57fc94

Fix many linkcheck errors, but not them all

d108dcb

use intersphinx for references to docs.astropy.org

Add a workflow for publishing to github pages

f75fd07

Merge remote-tracking branch 'upstream/main' into unified-theme-rewrite

2894e76

Cadair added 2 commits April 8, 2026 10:28

Address linkcheck errors

5e25664

bump to release theme

36733a0

eteq reviewed May 6, 2026

View reviewed changes

eteq merged commit 6962b36 into astropy:main May 6, 2026
6 of 8 checks passed

eteq mentioned this pull request May 6, 2026

Remove circleci webhook #706

Open

Uh oh!

Conversation

Cadair commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Cadair commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

pllim commented Jan 20, 2026

Uh oh!

Cadair commented Jan 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim commented Jan 21, 2026

Uh oh!

Cadair commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hamogu commented Jan 21, 2026

Uh oh!

hamogu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim commented Jan 22, 2026

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

pllim commented Jan 27, 2026

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

pllim commented Jan 27, 2026

Uh oh!

pllim commented Jan 27, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

pllim left a comment

Choose a reason for hiding this comment

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

Cadair commented Apr 7, 2026

Uh oh!

eteq left a comment

Choose a reason for hiding this comment

Uh oh!

eteq commented May 6, 2026

Uh oh!

eteq commented May 6, 2026

Uh oh!

Uh oh!

eteq commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Cadair commented Jan 19, 2026 •

edited

Loading

Cadair commented Jan 19, 2026 •

edited

Loading

Cadair commented Jan 21, 2026 •

edited

Loading